'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DI_PATH_BUS_ADDR 3DEVINFO "February 21, 2023"
.SH NAME
di_path_bus_addr, di_path_client_node, di_path_instance, di_path_node_name,
di_path_phci_node, di_path_state \- return libdevinfo path node information
.SH SYNOPSIS
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
#include <libdevinfo.h>

\fBchar *\fR\fBdi_path_bus_addr\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBdi_node_t\fR \fBdi_path_client_node\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBint\fR \fBdi_path_instance\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBchar *\fR\fBdi_path_node_name\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBdi_node_t\fR \fBdi_path_phci_node\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBdi_path_state_t\fR \fBdi_path_state\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.SH PARAMETERS
.ne 2
.na
\fB\fIpath\fR\fR
.ad
.RS 8n
The handle to a path node in a \fBdi_init\fR(3DEVINFO) snapshot.
.RE

.SH DESCRIPTION
These functions extract information associated with a path node.
.SH RETURN VALUES
The \fBdi_path_bus_addr()\fR function returns a string representing the pHCI
child path node's unit-address. This function is the \fBdi_path_t\fR peer of
\fBdi_bus_addr\fR(3DEVINFO).
.sp
.LP
The \fBdi_path_client_node()\fR function returns the \fBdi_node_t\fR of
the 'client' device node associated with the given path node. If the client device
node is not present in the current device tree snapshot, \fBDI_NODE_NIL\fR is
returned and \fBerrno\fR is set to \fBENOTSUP\fR.
.sp
.LP
The \fBdi_path_node_name()\fR function returns a pointer to a null-terminated
string containing the path node name. This function is the \fBdi_path_t\fR peer
of \fBdi_node_name\fR(3DEVINFO).
.sp
.LP
The \fBdi_path_instance()\fR function returns the instance number associated
with the given path node.  A path node instance is persistent across
\fBattach\fR(9E)/\fBdetach\fR(9E)and device reconfigurations, but not across
reboot.  A path node instance is unrelated to a device node
\fBdi_instance\fR(3DEVINFO).
.sp
.LP
The \fBdi_path_phci_node()\fR function returns the \fBdi_node_t\fR of the pHCI
host adapter associated with the given path node.  If the pHCI device node is
not present in the current device tree snapshot, \fBDI_NODE_NIL\fR is returned
and \fBerrno\fR is set to \fBENOTSUP\fR.
.sp
.LP
The \fBdi_path_state()\fR function returns the state of an I/O path. This
function may return one of the following values:
.sp
.ne 2
.na
\fB\fBDI_PATH_STATE_ONLINE\fR\fR
.ad
.sp .6
.RS 4n
Identifies that the \fBpath_info\fR node is online and I/O requests can be
routed through this path.
.RE

.sp
.ne 2
.na
\fB\fBDI_PATH_STATE_OFFLINE\fR\fR
.ad
.sp .6
.RS 4n
Identifies that the \fBpath_info\fR node is in offline state.
.RE

.sp
.ne 2
.na
\fB\fBDI_PATH_STATE_FAULT\fR\fR
.ad
.sp .6
.RS 4n
Identifies that the \fBpath_info\fR node is in faulted state and not ready for
I/O operations.
.RE

.sp
.ne 2
.na
\fB\fBDI_PATH_STATE_STANDBY\fR\fR
.ad
.sp .6
.RS 4n
Identifies that the \fBpath_info\fR node is in standby state and not ready for
I/O operations.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7)  for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.BR di_bus_addr (3DEVINFO),
.BR di_devfs_path (3DEVINFO),
.BR di_init (3DEVINFO),
.BR di_instance (3DEVINFO),
.BR di_node_name (3DEVINFO),
.BR di_path_client_next_path (3DEVINFO),
.BR di_path_prop_bytes (3DEVINFO),
.BR di_path_prop_lookup_bytes (3DEVINFO),
.BR di_path_prop_next (3DEVINFO),
.BR libdevinfo (3LIB),
.BR attributes (7)
.sp
.LP
\fIWriting Device Drivers\fR
